/* === LICENSE INFO ===
 * This source file is subject to the GPLv3 license that is bundled with this
 * package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://www.gnu.org/licenses/gpl.txt
 * === end of LICENSE INFO === */

/*==============================================================================
  File Name   : GDateTime.hpp
  Description : Declaration for GDateTime module of gUtil.

  Created on  : 2009-11-04
  Updated on  : 2011-02-04
  Updated by  : Lee Shiou Ming

  Cautions    : (important notes)
  ============================================================================*/

#ifndef GDATETIME_HPP_
#define GDATETIME_HPP_

#include <string>
#include <boost/date_time/local_time/local_time.hpp>


/**
 * @brief All gUtil modules will be wrapped within gUtil namespace.
 */
namespace gUtil
{
/**
 * @brief Namespace for GDateTime module.
 */
namespace GDateTime
{
    typedef boost::posix_time::ptime ptime;
    typedef boost::posix_time::second_clock second_clock;
    typedef boost::posix_time::microsec_clock microsec_clock;

    /**
     * @brief Defines different level of time precisions supported by GDateTime.
     *
     * Nanosecond precision is not supported yet.
     */
    enum TimePrecision
    {
        PRECISION_SECOND = 0,
        PRECISION_MILLESECOND,
        PRECISION_MICROSECOND
    };

    /**
     * @brief Obtain current date time.
     *
     * @return Current date time.
     */
    ptime getCurrentTime();

    /**
     * @brief Generates a string representation of date time specified by _now,
     *        output in ISO format: YYYY-MM-DD HH:MM:SS.
     *
     * @param _now
     * [IN] Specifies the date time to be formatted into string.
     * @param _precision
     * [IN] Optional parameter to specify the desired time precision.
     *
     * @return String representation of date time specified by _now. The exact
     *         format is controlled by _precision parameter:
     * - GDateTime::PRECISION_SECOND      ==> YYYY-MM-DD HH:MM:SS
     * - GDateTime::PRECISION_MILLESECOND ==> YYYY-MM-DD HH:MM:SS.fff
     * - GDateTime::PRECISION_MICROSECOND ==> YYYY-MM-DD HH:MM:SS.ffffff
     */
    std::string getDateTimeString(
            const ptime& _now,
            TimePrecision _precision = PRECISION_SECOND);

    /**
     * @brief Generates a string representation of current date time in ISO
     *        format: YYYY-MM-DD HH:MM:SS.
     *
     * @param _precision
     * [IN] Optional parameter to specify the desired time precision.
     *
     * @return String representation of current date time. The exact format is
     *         controlled by _precision parameter:
     * - GDateTime::PRECISION_SECOND      ==> YYYY-MM-DD HH:MM:SS
     * - GDateTime::PRECISION_MILLESECOND ==> YYYY-MM-DD HH:MM:SS.fff
     * - GDateTime::PRECISION_MICROSECOND ==> YYYY-MM-DD HH:MM:SS.ffffff
     */
    std::string getDateTimeString(TimePrecision _precision = PRECISION_SECOND);

    /**
     * @brief Generates a string representation of date specified by _now,
     *        output in ISO format.
     *
     * @param _now
     * [IN] Specifies the date to be formatted into string.
     * @param _isDelimited
     * [IN] Indicates if the format should contains a delimiter.
     *
     * @return String representation of current time. The exact format is
     *         controlled by _isDelimited parameter:
     * - true  ==> YYYY-MM-DD
     * - false ==> YYYYMMDD
     */
    std::string getDateString(const ptime& _now, bool _isDelimited = true);

    /**
     * @brief Generates a string representation of current date in ISO format.
     *
     * @param _isDelimited
     * [IN] Indicates if the format should contains a delimiter.
     *
     * @return String representation of current time. The exact format is
     *         controlled by _isDelimited parameter:
     * - true  ==> YYYY-MM-DD
     * - false ==> YYYYMMDD
     */
    std::string getDateString(bool _isDelimited = true);

    /**
     * @brief Generates a string representation of time specified by _now.
     *
     * @param _now
     * [IN] Specifies the time to be formatted into string.
     * @param _precision
     * [IN] Optional parameter to specify the desired time precision.
     * @param _isDelimited
     * [IN] Indicates if the format should contains a delimiter.
     *
     * @return String representation of current time. The exact format is
     *         controlled by _isDelimited parameter:
     * - true  ==> HH:MM:SS
     * - false ==> HHMMSS
     */
    std::string getTimeString(
            const ptime& _now,
            TimePrecision _precision = PRECISION_SECOND,
            bool _isDelimited = true);

    /**
     * @brief Generates a string representation of current time.
     *
     * @param _precision
     * [IN] Optional parameter to specify the desired time precision.
     * @param _isDelimited
     * [IN] Indicates if the format should contains a delimiter.
     *
     * @return String representation of current time. The exact format is
     *         controlled by _isDelimited parameter:
     * - true  ==> HH:MM:SS
     * - false ==> HHMMSS
     */
    std::string getTimeString(
            TimePrecision _precision = PRECISION_SECOND,
            bool _isDelimited = true);

}  /* end of namespace GDateTime */
}  /* end of namespace gUtil */

#endif  /* GDATETIME_HPP_ */
